Microsoft CodeView and Utilities
================================
CHAPTER 9 ___ EXAMINING CODE

Several CodeView commands allow you to examine program code or data related to 
code.  The following commands are discussed in this chapter:

Command			Action
-------------------------------
Set Mode (S)		Sets format for code displays
Unassemble (U)		Displays assembly instructions
View (V)		Displays source lines
Current Location (.)	Displays the current location line
Stack Trace (K)		Displays routines or procedures

9.1  Set Mode Command

The Set Mode command sets the mode in which code is displayed.  The two basic 
display modes are source mode, in which the program is displayed as source 
lines, and assembly mode, in which the program is displayed as assembly 
language instructions.  These two modes can be combined in mixed mode, in 
which the program is displayed with both source lines and assembly language 
instructions.

In sequential mode, there are three display modes: source, assembly, and 
mixed.  These modes affect the output of commands that display code (Register, 
Trace, Program Step, Go, Execute, and Unassemble).

In window mode, these same display modes are available, but affect what kind 
of code appears in the display window.

Source and mixed modes are only available if the executable file contains 
symbols in the CodeView format.  Programs that do not contain symbolic inform-
ation (including all .COM files) are displayed in assembly mode.

<*> Mouse

To set the display mode with the mouse, point to View on the menu bar, press a 
mouse button and drag the highlight to either the Source selection for source 
mode, the Mixed selection for mixed mode, or the Assembly selection for assem-
bly mode.  Then release the button.

You can further control the display of assembly language instructions by 
making selections from the Options menu.  See Section 2.1.3.6, "The Options 
Menu," for more information.

<*> Keyboard

To change the display mode with a keyboard command, press the F3 key.  This 
will rotate the mode to the next setting; you may need to press F3 twice to 
get the desired mode.  This command works in either window or sequential mode.  
In sequential mode, the word  source, mixed, or assembly  is displayed to 
indicate the new mode.

<*> Dialog

To set the display mode from the dialog window, enter a command line with the 
following syntax:

S[+|-|&]

If the plus sign is specified (S-), source mode is selected, and the word 
source is displayed.

If the minus sign is specified (S-), assembly mode is selected, and the word 
'assembly' is displayed.  In window mode, the display will include any 
assembly options, except the Mixed Source option, previously toggled on from 
the Options menu.  The Mixed Source option is always turned off by the S- 
command.

If the ampersand is specified (S&), mixed mode is selected, and the word 
'mixed' is displayed.  In window mode, the display will include any assembly 
options previously toggled on from the Options menu.  In addition, the Mixed 
Source option will be turned on by the S& command.

If no argument is specified (S), the current mode (source, assembly, or mixed) 
is displayed.

The Unassemble command in sequential mode is an exception in that it displays 
mixed source and assembly with both the source (S+) and mixed (S&) modes.  
When you enter the dialog version of the Set Mode command, the CodeView 
debugger outputs the name of the new display mode:
source, assembly, or mixed.

<*> Examples

>S+
source
>S-
assembly
>S&
mixed
>

The examples above show the source mode being changed to  source, assembly, 
and mixed.  In window mode, the commands change the format of the display 
window.  In sequential mode, the commands change the output from the commands 
that display code (Register, Trace, Program, Step, Go, Execute, and 
Unassemble).  See the sections on individual commands for examples of how they 
are affected by the display mode.

9.2  Unassemble Command

The Unassemble command displays the assembly-language instructions of the 
program being debugged.  It is most useful in sequential mode, where it is the 
only method of examining a sequence of assembly language instructions.  In 
window mode it can be used to display a specific portion of assembly language 
code in the display window.
----
Note
----
Occasionally, code similar to the following will be displayed:

FE30    ???    Byte Ptr   [BX + SI]

If you attempt to unassemble data, then the CodeView debugger may display
meaningless instructions.
====

<*> Mouse

The Unassemble command has no direct mouse equivalent, but you can view 
unassembled code at any time by changing the mode to assembly or mixed (see 
Section 9.1, "Set Mode Command," for more information).

<*> Keyboard

The Unassemble command has no direct keyboard equivalent, but you can view 
unassembled code at any time by changing the mode to assembly or mixed (see 
Section 9.1, "Set Mode Command," for more information).

<*> Dialog

To display unassembled code using a dialog command, enter a command line with 
the following syntax:

U [address | range]

The effect of the command varies depending on whether you are in sequential or 
window mode.

In sequential mode, if you do not specify  address or  range, the disassembled 
code begins at the current unassemble address and shows the next eight lines 
of instructions.  The unassemble address is the address of the instruction 
after the last instruction displayed by the previous Unassemble command.  If 
the Unassemble command has not been used during the session, the unassemble 
address is the current instruction.

If you specify an address, the disassembly starts at that address and shows 
the next eight lines of instructions.  If you specify a  range, the 
instructions within the range will be displayed.

The sequential mode format of the display depends on the current display mode 
(see Section 9.1, "Set Mode Command," for more information).  If the mode is 
source (S+) or mixed (S&), the CodeView debugger displays source lines mixed 
with unassembled instructions.  One source line is shown for each corresponding 
group of assembly language instructions.  If the display mode is assembly, 
only assembly language instructions are shown.

In window mode, the Unassemble command changes the mode of the display window 
to assembly.  The display format will reflect any options previously set from 
the Options menu.  There is no output to the dialog window.  If address is 
given, the instructions in the display window will begin at the specified 
address.  If range is given, only the starting address will be used.  If no 
argument is given, the debugger scrolls down and displays the next screen of 
assembly language instructions.
----
Note
----
The 80286 protected mode mnemonics (also avaialble with the 800386) cannot 
be displayed with the Unassemble command.
====

<*> Examples

>S&
mixed
>U 0x11
49D0:0011 35068E	XOR   AX,__sqrtjmptab+8cd4 (8E06)
49D0:0014 189A2300	SBB   Byte Ptr [BP+SI+0023],BL
49D0:0018 FC		CLD
49D0:0019 49		DEC   CX
49D0:001A CD351ED418	INT   35   ;FSTP	DWord Ptr [__fpinit+ee (18D4)]
49D0:001F CD3D		INT   3D   ;FWAIT
7:		A = 0.0
49D0:0021 CD35EE	INT   35   ;FLDZ

The sequential mode example above sets the mode to mixed and unassembles eight 
lines of machine code, plus whatever source lines are encountered within those 
lines.  The display would be the same if the mode were source.

The example is taken from a FORTRAN debugging session, but produces results 
similar to what woud be produced using the same commands with a C or BASIC 
programs.

>S-
assembly
>U 0x11
49D0:0011 35068E	XOR   AX,__sqrtjmptab+8cd4 (8E06)
49D0:0014 189A2300	SBB   Byte Ptr [BP+SI+0023],BL
49D0:0018 FC		CLD
49D0:0019 49		DEC   CX
49D0:001A CD351ED418	INT   35  ;FSTP   DWord Ptr [__fpinit+ee (18D4)]
49D0:001F CD3D		INT   3D  ;FWAIT
49D0:0021 CD35EE	INT   35  ;FLDZ
>

The sequential mode example above sets the mode to assembly and repeats the 
same command.

9.3  View Command

The View command displays the lines of a text file (usually a source module or 
include file).  It is most useful in sequential mode, where it is the only 
method of examining a sequence of source lines.  In window mode, the View 
command can be used to page through the source file or to load a new source 
file.

<*> Mouse

To load a new source file with the button, point to File on the menu bar, 
press a mouse button and drag the highlight to the Load selection, then 
release the button.  A dialog box appears, asking for the name of the file you 
wish to load.  Type the name of the file, and press the ENTER key or a mouse 
button.  The new file appears in the display window.

The paging capabilities of the View command have no direct mouse equivalent, 
but you can move about in the source file by pointing to the up or down arrows 
on the scroll bars and then clicking different mouse buttons.  See Section 
2.1.2.2, "Controlling Program Execution with the Mouse," for more information.

<*> Keyboard

To load a new source file with a keyboard command, press ALT+F to open the 
File menu, then press L to select Load.  A dialog box appears asking for the 
name of the file you wish to load.  Type the name of the file, and press the 
ENTER key.  The new file appears in the display window.

The paging capabilities of the View command have no direct keyboard 
equivalent, but you can move about in the source file by first putting the 
cursor in the display window with the F6 key, then pressing the PGUP, PGDN, 
HOME, END, UP ARROW, and DOWN ARROW keys.  See Section 2.1.1.3, "Controlling 
Program Execution with Keyboard Commands," for more information.

<*> Dialog

To display source lines using a dialog command, enter a command line with the 
following syntax:

V [expression]

Since addresses for the View command are often specified as a line number 
(with an optional source file), a more specific syntax for the command would 
be as follows:

V [.[filenames]linenumber]

The effect of the command varies, depending on whether you are in sequential 
or window mode.

In sequential mode, the View command displays eight source lines.  The 
starting source line is one of the following:

*	The current source line if no argument is given.

*	The specified linenumber. If filename is given, the specified file is 
	loaded, and the linenumber refers to lines in it.

*	The address that expression evaluates to. For example, expression 
	could be a procedure name or an address in the segment:offset format.
	The code segment is assumed if no segment is given.

In sequential mode, the View command is not affected by the current display 
mode (source, assembly, or moxed); source lines are displayed regardless of 
the mode.

In window mode, if you enter the View command while the display mode is 
assembly, the CodeView debugger will automatically switch back to source mode.  
If you give linenumber or expression, the display window will be redrawn so 
that the source line corresponding to the given address will appear at the top 
of the source window.  If you specify a filename with a linenumber, the 
specified file will be loaded.

If you enter the View command with no arguments, the display will scrill down 
one line short of a page; that is, the source line that was at the bottom of 
the window will be at the top.
----
Note
----
The View command with no argument is similar to pressing the PGDN key, or 
clicking right on the down arrow with the mouse.  The difference is that 
pressing the PGDN key enables you to scroll down one more line.
====

<*> Examples

>V BUBBLE		;* Example 1, FORTRAN source code
51:		IF (N .LE. 1) GOTO 101
52:		DO 201 I = 1,N-1
53:		DO 301 J = I + 1,N
54:		IF (X(I) .LE. X(J)) GOTO 301
55:		TEMP = X(I)
56:		X(I) = X(J)
57:		X(J) = TEMP
58:	    301 CONTINUE

Example 1 (shown in sequential mode) displays eight source lines, beginning at 
routine BUBBLE.

>V .math.c:30	;* Example 2, C source code
30:		   register int j;
31:
32:		   for (j = q; j >= 0; j--)
33:			   if (t[j] + p[j] > 9) {
34:				   p[j] += t[j] - 10;
35:				   p[j-1] += 1;
36:			   } else
37:		   p[j] += t[j];
>

Example 2 loads the source file  math.c and displays eight source lines 
starting at line 30.

All forms of the View command are supported with all languages that work with 
the CodeView debugger.

9.4  Current Location Command

The Current Location command displays the source line or assembly language 
instruction corresponding to the current program location.

<*> Mouse

The Current Location command cannot be executed with the mouse.

<*> Keyboard

The Current Location command cannot be executed with a keyboard command.

<*> Dialog

To display the current location line using a dialog command, enter a command 
line with the following syntax (a period only):

.

In sequential mode, the command displays the current source line.  The line is 
displayed regardless of whether the current debugging mode is source or 
assembly.  If the program being debugged has no symbolic information, the 
command will be ignored.

In window mode, the command puts the current program location (marked with 
reverse video or a contrasting color) in the center of the display window.  
The display mode (source or assembly) will not be affected.  This command is 
useful if you have scrolled through the source code or assembly language 
instructions so that the current location line is no longer visible.

For example, if you are in window mode and have executed the program being 
debugged to somewhere near the start of the program, but you have scrolled tha 
display to a point near the end, the Current Location command returns the 
display to the current program location.

<*> Example

>.
MINDAT = 1.0E6
>

The example above illustrates how to display the current source line in 
sequential mode.  The same command in window mode would not produce any 
output, but it could change the text that is shown in the display window.

9.5  Stack Trace Command

The Stack Trace command allows you to display routines that have called during 
program execution (see note below).  The first line of the display shows the 
name of the current routine.  The succeeding lines (if any) list any other 
routines that were called to reach the current address.  The dialog version of 
the Stack Trace command also displays the source lines where each routine was 
called.

For each routine, the values of any arguments are shown in parentheses after 
the routine name.  Values are shown in the current radix (the default is 
decimal).

The term "stack trace" is used because, as each routine is called, its address 
and arguments are stored on (pushed onto) the program stack.  Therefore, 
tracing through the stack shows the currently active routines.  With C and 
FORTRAN programs, the  main  routine will always be at the bottom of the 
stack.  With BASIC programs, the main program is not listed on the stack, 
because BASIC programs have no standard label (such as  main) corresponding to 
the first line of a program.  Only routines called by the main program will be 
displayed.  In assembly language programs, the bottom routine displayed in the 
stack trace is  astart  instead of  main.
----
Note
----
This discussion uses the term "routines," which is a general term for 
functions (C, FORTRAN, Pascal), subroutines (FORTRAN), procedures (Pascal), 
and subprograms and function procedures (BASIC)--each of which uses the 
stack to transfer control to an independent program unit.  In assembly mode
the term "procedure" may be more accurate.  GOSUB and DEF FN routines in 
BASIC will not work with the Stack Trace command since they do not follow 
the same convention for setting up the stack.

If you are using the CodeView debugger to debug assembly language programs, 
the Stack Trace command will work only if procedures were called with the 
calling used by Microsoft languages.  This calling convention is explained 
in the Microsoft Mixed-Language Programming Guide.
====

<*> Mouse

To view a stack trace with the mouse, point to Calls on the menu bar and press 
a mouse button.  The Calls menu will appear, showing the current routine at 
the top and other routines below it in the reverse order in which they were 
called; for example, the first routine called (which is always  main  in a C 
or FORTRAN program) will be at the bottom.  The values of any routine 
arguments will be shown in parentheses following the routines.

If you want to view one of the routines that was previously called, select the 
routine by dragging down the highlight to the routine you wish to see, then 
releasing the mouse button.  (You can also select a routine by clicking a 
selection, once the menu is open.)  The effect of selecting a routine in the 
Calls menu is to cause the debugger to display that routine.  The cursor will 
be on the last statement that was executed in the routine.

<*> Dialog

To display a stack trace with a dialog command, enter a command line with the 
following syntax:

K

The output from the Stack Trace dialog command lists the routines in the 
reverse order in which they were called.  The arguments to each routine are 
shown in parentheses.  Finally, the line number from which the routine was 
called is shown.

You can enter the line number as an argument to the View or Unassemble command 
if you want to view code at the point where the routine was called.  In window 
mode, the output from the Stack Trace dialog command appears in the dialog 
window.

<*> FORTRAN Example

>K
ANALYZE(67,0), line 94
COUNTWORDS(0,512), line 73
MAIN(2,5098), line 42
>

In the example above, the first line of output indicates that the current 
routine is ANALYZE.  Its first argument currently has a decimal value of 67, 
and its second argument has a value of 0.  The current location in this 
routine is line 94.

The second line indicates that ANALYZE was called by COUNTWORDS, and that its 
arguments have the values 0 and 512.  Routine ANALYZE was called from line 73 
of routine COUNTWORDS.

Likewise, COUNTWORDS was called from line 42 of MAIN, and its arguments have 
the values 2 and 5098.

If the radix had been set to 16 or 8 using the Radix (N) command, the 
arguments would be shown in that radix.  For example, the last line would be 
shown as MAIN(2,13ea) in hexadecimal or MAIN(2,11752) in octal.

<*> C Example

>K
analyze(67,0), line 94
countwords(0,512), line 73
main(2,5098)
>

As with the FORTRAN example, the example above shows the routines on the stack 
in the reverse order in which they were called.  Since  analyze  is on the 
top, it has been called most recently; in other words, it is the current 
routine.

Each routine is shown with the arguments it was passed, along with the last 
source line that it had been executing.  NOte that  main  is shown with the 
command line arguments  argc  (which is equal to 2) and argv (which is a 
pointer equal to 5098 decimal).  Since the language is C, main will always be 
on the bottom of the stack.

<*> BASIC Example

>K
ROLL#(19122:6040)
MAKE#(19122:6040)
CALC(19122:5982, 19122:5990)
>

As with the FORTRAN example, the example above shows the routines on the stack 
in the reverse order in which they were called.  Since ROLL# is on the top, it 
has been called most recently; in other words, it is the current routine.

Each routine is displayed along with the arguments by which it was passed.  In 
BASIC, arguments passed to routines are always addresses.

This example shows some features peculiar to BASIC.  First of all, there is no 
MAIN displayed, because the BASIC compiler does not produce any such symbol.  
Furthermore, each routine will have a type tag if it is a function; the tag 
indicates what the function returns.  ROLL# and MAKE# are both functions 
returning a double-precision floating point.  A function that returned a short 
integer would have a % type tag.  CALC has no type tag since it is a 
subprogram, and therefore does not return a value of any type.



.end chapter.